系列：30 天打造企業級 PLM｜面向：全端｜素材：Import 模組（ImportJob）、Part/BOM 匯入通道

問題場景

「我有三千筆料號要建，總不能一筆一筆敲吧？」批次匯入是上線初期最被依賴的功能。舊資料要進來（Day 23–24 的下游），供應商給的料表要進來，工程師整理的 Excel 也要進來。但它同時是最容易出事的功能。三千筆裡第 1847 筆炸了怎麼辦？匯到一半使用者關瀏覽器了怎麼辦？誰匯的、匯了什麼，三個月後查得到嗎？

一般使用者匯入頁與管理端 Part/BOM 匯入通道實機畫面:

商業邏輯設計

• 匯入要不要走簽核？大量建料是高風險動作，但三千筆各跑一次簽核是行政災難。取捨的結果是不逐筆走 workflow，改用稽核表單收口：Part/BOM 遷移匯入以批次為單位掛一張 MIGRATION 表單，批次整體有人負責、有紀錄可查。系統保留了一個 System reserved 的 MIGRATION Form Type 專門幹這件事
• 匯入通道分兩級。一般使用者匯入自己的料，走完整業務驗證，量小；管理員遷移匯入處理 Day 23 的搬遷資料，驗證放寬，量大。權限與能力分級，別想用一個功能打天下
• 範本 → 預覽 → 套用三段式，讓使用者在真的寫進去之前先看到會發生什麼。預覽是匯入功能的安全帶，省下的是「匯錯了幫我清資料」的支援成本

技術選型與取捨

架構演進：從 Agile Import Wizard 同步卡死到非同步背景 Worker

以前在 Oracle Agile PLM 操作批次匯入（Import Wizard）時，使用者常有「如履薄冰」的焦慮感：

1. 同步阻塞與超時崩潰：舊匯入精靈是在單一 EJB 請求中同步執行，資料量一大多跑幾分鐘，瀏覽器或 WebLogic 就噴出 504 Gateway Timeout 或 Transaction Timeout；
2. 缺乏背景推進與進度回報：匯入期間使用者必須死盯著瀏覽器轉圈圈，一旦手滑關閉視窗，完全不知道幾千筆資料卡在第幾行；
3. 錯誤排查痛苦：失敗時只產出一份晦澀的伺服器 log 檔，無法精準告訴使用者哪幾行格式錯誤。

Mini-PLM 採用非同步背景工作器（ImportJob）+ SSE 即時進度推播：

同步處理 vs 背景任務

幾十筆同步處理沒問題；幾千筆讓瀏覽器掛著等 HTTP 回應，等到的多半是 timeout。所以 apply 走非同步：API 立即回 jobId，實際工作進 ImportJob 背景執行，前端輪 progress 或收 SSE，使用者可以自由切換分頁或關閉瀏覽器。

錯誤策略：整批回滾 vs 跳過續跑

「一筆錯全部不進」聽起來嚴謹，實務上是折磨。三千筆修一筆重傳一次，永遠傳不完。Mini-PLM 選擇分塊處理加錯誤列清單：壞的跳過、好的進去，結束後給「成功 2953 / 失敗 47 + 每筆原因」的結果報告，使用者修 47 筆重傳就好。例外是遷移通道的結構性資料（BOM 父子關聯），父件失敗子件必須跟著跳，錯誤有連鎖語意。

欄位對應（mapping profile）可儲存

Excel 欄位 → 系統欄位（Day 4 的 metadata 又出現了）的對應設定可以存成 profile 重用。供應商每月給同格式的料表，對應設一次就好。匯入設定本身也是資料，跟 Day 11 trigger 的哲學一致。

核心內容：ImportJob 的工程細節

上傳檔案 → 解析驗證（同步，快）→ 預覽差異
  → apply（非同步）：ImportJob 建立
      → 分塊處理（每塊 N 筆，塊完成即更新進度）
      → 進度持久化（job 狀態存 DB，不是存記憶體）
      → SSE 推進度（Day 19 的通道）＋完成全域通知
      → 匯入歷史落檔（誰、何時、檔名、成功/失敗筆數）

設計上有兩件事特別要顧：

1. 進度持久化。job 狀態存 DB 而非 session 或記憶體，使用者關瀏覽器、切頁面，回來還看得到進度與結果；重新整理後前端以 jobId 續接
2. 版本語意要明確。匯入既有料號時是蓋掉還是開新版？答案跟著通道走：一般匯入更新 Draft 版；遷移通道以 $REVISION 語意支援「表單驅動開新版」（接 Day 13 的機制），搬遷含版本歷程的走 Part/BOM Migration 專用通道

踩坑記錄

• 完成通知在使用者導頁後才到。小量匯入幾秒就完成，使用者早已切去別頁，所以完成通知做成全域（Day 19 的通知系統），不綁在匯入頁面上。E2E 專門有一條「送出後立即導頁仍收到通知」的測試，260 列跨 200 分塊的進度遞增也在測試裡驗過
• 筆數大時的預覽成本。預覽如果對每筆做完整驗證，三千筆的預覽本身就要跑很久。做法是預覽限量抽驗、全量只做結構檢查，完整驗證留給 apply 階段逐塊做
• Excel 解析的地雷日常：前導零被 Excel 吃掉（料號 "0012" 變 12）、日期被自動轉格式。範本欄位一律文字格式，解析端再做型別轉換

小結

三段式當安全帶，背景任務加進度持久化撐起大批量，錯誤清單策略顧可用性，稽核表單收口負責問責。批次匯入把這幾件事做齊，上線初期就能少接很多支援電話。明日 Day 27：一套程式支援兩種資料庫——PostgreSQL 與 Oracle 並存的血淚全集。